net.sf.surrogate.core
Class SurrogateCalls

java.lang.Object
  |
  +--net.sf.surrogate.core.SurrogateCalls

public abstract class SurrogateCalls

extends java.lang.Object

Abstract aspect for use with the Surrogate framework. This aspect provides the standard interaction with the SurrogateManager. Instead of coding relatively complex advices, the user only needs to create a concrete implementation of the SurrogateCalls advice, and implement the mockPointcut pointcut. The advices then handles the standard processing towards the SurrogateManager.

An example implementation is

     aspect MyCalls extends SurrogateCalls {
   
       protected pointcut mockPoincut() : 
         (
           execution(* com.mycompany.MyClass.getOrder(..) ) ||
           call (java.io.*Writer.new(..)) ||
           call(* java.lang.System.currentTimeMillis())
         ) ;
    }
 

and an example "difficult-to-test or mock" java class is:

    package com.mycompany;
    import java.io.*;
  
    public class MyClass {
    
      public static final Order getOrder(String orderId) {
        Writer out = new BufferedWriter(
               new FileWriter("D:/production/customer_name.log"));
        out.write(orderId);
        return new Order(System.currentTimeMillis());
      }
      ....
   }
 

Since the method is final and contains calls to external, varying entities (system time and external file), it is normally difficult to 1) replace the "getOrder" method by a mock and 2) test the internals of the method. Surrogate provides a solution to this problem. The advice would, when woven with the "classes-under-test", allow you to substitute mock objects for the following:

• Every time com.mycompany.MyClass.getOrder executes. You could override the method by a corresponding "mock method" using the addMockMethod, or override the method execution and return value by using the addMock method.
• Every time a "Writer" in the "java.io" package is instantiated from within the classes-under-test. You could override the BufferedWriter and/or FileWriter with a custom-made mock Writer extending the class. The mock is added using the addMock method.
• Every time the classes-under-test call System.currentTimeMillis(). You could control the time returned by using the addMockMethod

Pointcut Summary
protected	mockPointcut() Defines the pointcut allowing to substitute method return values with a mock object implementation or to substitute a method call or method execution with a MockMethod.

Advice Summary

around(): mockPointcut..
Executes when a mockPointcut pointcut is detected.

null

Constructor Summary

SurrogateCalls()

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Pointcut Detail

mockPointcut()

Defines the pointcut allowing to substitute method return values with a mock object implementation or to substitute a method call or method execution with a MockMethod. Resulting implementations of this pointcut must be method or constructor pointcuts.

Note: If you define a pointcut on a method returning, say java.lang.Object be aware of that the return value almost certainly will be subsituteted by any mock object, since all Objects inherits from java.lang.Object.

Advice Detail

around

around(): mockPointcut..

Executes when a mockPointcut pointcut is detected. If a mock has been registered, that object is allowed to execute, otherwise, the original code is allowed to proceed.

Throws Throwable - any Throwable thrown by the SurrogateManager or executing mock is catched and rethrown.

See also SurrogateManager.getMockExecutor ExceptionThrower

null

Constructor Detail

SurrogateCalls

public SurrogateCalls()